; Improve documentation of change hooks

* doc/lispref/text.texi (Change Hooks): Warn against buffer
changes in the hook functions.  (Bug#79115)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 8329a67d6c2d4f6dd2ceb10aeba6bf6e3686ed70..dc35e93f2da336227930d5a0b6771a6cc33cb97e 100644 (file)
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -6291,7 +6291,11 @@ specific parts of the text.
   The functions you use in these hooks should save and restore the match
 data if they do anything that uses regular expressions; otherwise, they
 will interfere in bizarre ways with the editing operations that call
-them.
+them.  In addition, the functions in these hooks should avoid changing
+buffer text, faces, properties, overlays, and other aspects of the
+buffer-specific state except those that the hook functions themselves
+create and manage, because other parts of Emacs might become confused by
+such changes behind their back.
 
 @defvar before-change-functions
 This variable holds a list of functions to call when Emacs is about to